home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / FREENET / HOWAT / FT131-13.SPK / !FreeTerm / !Help next >
Text File  |  1997-09-21  |  18KB  |  510 lines
  1.  
  2.  
  3.                     The FreeTerm Terminal Emulator
  4.  
  5.                                Freeware
  6.              (C) Tony Howat & Merlin Hughes 1995, 1996, 1997
  7.  
  8.  
  9. 0. Copyright
  10.  
  11.   The FreeTerm application is (C) Tony Howat 1995->7, with the SICKTerm
  12.   terminal library (C) Merlin Hughes, but is released as freeware.
  13.   This means that you may copy and distribute it, subject to certain
  14.   conditions.
  15.  
  16.   Specifically, as an individual, you may only charge to cover the cost
  17.   of distributing it, and you may not use it to make money directly or
  18.   indirectly (by using it as an incentive to buy something else for
  19.   example).
  20.  
  21.   Any company which wishes to include the program on a magazine disc or
  22.   disc which will be sold *must* contact us to discuss arrangements.
  23.  
  24.   It is also imperative that anyone considering including FreeTerm in a
  25.   internet suite of any sort (free or otherwise) contacts me (Tony Howat).
  26.  
  27.   Contact Tony Howat if you are unsure of how these terms affect you.
  28.  
  29.   FreeTerm should only be distributed with the whole contents of the
  30.   original archive, with all files unmodified.
  31.  
  32.   SICKTerm makes use of ZapRedraw, (C) Dominic Symes 1994.
  33.   The project was started by Tom Hughes, author of FreeNet.
  34.  
  35.   None of the authors accept any responsibility for any
  36.   loss/damage/whatever resulting from the use of FreeTerm. It is
  37.   supplied "as is".
  38.  
  39. 1. Contents
  40.  
  41.   0.    ... Copyright
  42.   1.    ... Contents
  43.   2.    ... Introduction
  44.   3.    ... Basic use of FreeTerm
  45.   3.1   ... Downloading and Uploading text
  46.   3.2   ... Disconnection
  47.   3.3   ... Using finger
  48.   3.4   ... The Host and Port Menus
  49.   3.5   ... The FreeScript language
  50.   3.5.1 ... Points to note
  51.   3.5.2 ... Adding Scripts to the Hotlist
  52.   3.6   ... CLI options
  53.   3.7   ... The AutoRun Directory
  54.   4.    ... Miscellaneous notes
  55.   4.1   ... StrongARM Compatibility
  56.   4.2   ... Programmers' guff
  57.   4.3   ... Internationalisation
  58.   5.    ... Contacting the authors
  59.  
  60. 2. Introduction
  61.  
  62.   The FreeTerm application is a terminal emulator for use with any
  63.   TCP/IP stack that supports the Acorn sockets interface. Currently
  64.   that means either the Acorn TCP/IP stack, FreeNet or any of the
  65.   commercial suites except Termite.
  66.  
  67.   Currently the application provides support for straightforward
  68.   telnet and finger, and display sessions in a window which emulates
  69.   a VT102 or VT52 series terminal. However, according to the beta
  70.   testers it performs these basic functions rather well, and reliably,
  71.   which is what matters.
  72.  
  73. 3. Using FreeTerm
  74.  
  75.   Starting FreeTerm places an icon on the iconbar, and clicking on
  76.   this provides a dialogue box with two writeable icons. The first
  77.   of these takes the host name (or IP address), and the second
  78.   the port number (or service name). Leaving the port
  79.   number blank will cause it to default to the standard telnet
  80.   port. Both the host and port writable icons are accompanied by
  81.   pop up menus, and there is also a hot list on the icon bar
  82.   menu. See the section 4 of this manual for details on how to set
  83.   up these menus.
  84.  
  85.   Selecting certain ports (in this current version this will only
  86.   occur with "finger") will cause the dialogue box to expand and
  87.   display and extra arguments field for extra parameters needed
  88.   to establish a certain kind of connection.
  89.  
  90.   Clicking on the connect button causes FreeTerm to establish a
  91.   connection to the specified address, and then open a terminal
  92.   window for the connection. For connections to the default telnet
  93.   port, this window will default to character mode (where each
  94.   character you type is transmitted straight away) if that is
  95.   acceptable to the remote host, otherwise line mode is used.
  96.  
  97. 3.1. Downloading and Uploading text.
  98.  
  99.   To send a file down the telnet connection drag it to the window. To
  100.   save text from a telnet window highlight it, and drag it to a filer
  101.   window.
  102.  
  103.   To download long chunks of text it is best to use the spooler, use
  104.   the "Spool>Open" save as dialogue to locate your spoolfile and
  105.   start recording. The spool may be paused, and selecting the
  106.   "Spool>Strip" option will filter control codes from the output.
  107.   When you have finished spooling click "Spool>Close"
  108.  
  109.   NB : FreeTerm only handles text downloads and uploads, ZModem
  110.        transfers may be implemented in the future.
  111.  
  112. 3.2. Disconnection
  113.  
  114.   Closing a terminal window will result in the connection to the
  115.   remote host being dropped, whilst the remote host dropping an open
  116.   connection will result in a message in the terminal window.
  117.  
  118. 3.3. Using finger
  119.  
  120.   Finger is an internet service for finding out who is using a system,
  121.   or finding out about users on a system. FreeTerm includes a finger
  122.   client. To use it enter a hostname in the normal way and select
  123.   "Finger" as the port, the connect window will grow an extra
  124.   writeable icon, this is where you enter the finger string.
  125.  
  126.   The finger string specifies what information you want from the
  127.   remote system. The most common types of finger strings are
  128.   listed below.
  129.  
  130.   <Blank>  - An empty finger string lists all the users on a system.
  131.   user     - Entering a valid username returns information on a
  132.              specific user.
  133.  
  134.   ...you can use the @ character to finger via the system you are
  135.   connecting to. So :
  136.  
  137.   @wibble.com     - lists the users on wibble.com via the system you
  138.                     actually connected to.
  139.   jack@wibble.com - gets information on the user 'jack' on wibble.com
  140.                     via the system you actually connected to.
  141.  
  142.   You can use as many @'s as you need, but at most you should only
  143.   need one if you ever need to finger through a firewall. 
  144.  
  145.   For more information on finger see RFC1288.
  146.  
  147. 3.4. The host and port menus
  148.  
  149.   The connection dialogue features two writeable icons for entering
  150.   the port name/number and the host you wish to connect to. Hostnames
  151.   are usually fairly long, and on a local network with only a few
  152.   hosts typing the same thing each time you wish to connect to a host
  153.   soon becomes tiresome. FreeTerm v0.12 and later solve this by way
  154.   of pop up menus, which are triggered by a button alongside each
  155.   writeable icon. The host menu lists entries in the format :
  156.  
  157.   foo.bar.co.uk (Telnet)
  158.   moo.cow.com (Finger)
  159.   wibble.zonk.org
  160.   ...
  161.  
  162.   The port name in brackets is the default port, not all entries may
  163.   have a default port. Clicking on an entry in the menu fills in the
  164.   writable fields in the connection box with the hostname and portname
  165.   (if present), leaving you to press the "Connect" button.
  166.  
  167.   The icon bar hot list is exactly the same as the host menu, except
  168.   that if you click on an entry with both a default port and host name
  169.   the connection starts immediately. If the entry has no default port
  170.   the connect dialogue box is displayed for you to enter a portname.
  171.  
  172.   The port menu simply lists frequently used portnames, clicking on an
  173.   entry in the menu copies the portname to the writeable icon.
  174.  
  175.   The contents of the host menu/hotlist and port menu are read from
  176.   configuration files in !FreeUser.Files.FreeTerm, namely HostList
  177.   and PortList. The format of these files is explained in their
  178.   comments.
  179.  
  180.   In older versions of FreeTerm you hand edit these files, you still
  181.   can, but there is now a user interface in the configuration window
  182.   (accessable from the iconbar 'Configure' option).
  183.  
  184. 3.5. The FreeScript language
  185.  
  186.   The FreeScript language is basically designed to log you into
  187.   machines automatically. For this reason it's very basic, although
  188.   more commands and structures may be added in future.
  189.  
  190.   FreeScript files are text files of type "FScript" (&133).
  191.  
  192.   The best way to introduce their example, so here is a script I use
  193.   to log into my university account and fire up pine (a mail/news
  194.   reader) :
  195.  
  196.   # log into loki and start pine
  197.  
  198.   session telnet loki.brunel.ac.uk
  199.     waitfor "ogin:"
  200.     sendl   "cs96arh"
  201.     waitfor "word:"
  202.     sendl   "password"
  203.     waitfor "loki%"
  204.     sendl   "pine"
  205.   sessionend
  206.  
  207.   Saving that as a file of type &133 and double clicking it will start
  208.   FreeTerm and start the script. Obviously the password isn't correct.
  209.  
  210.   More usefully, here's a script to connect to archie at the Imperial
  211.   college sunsite :
  212.  
  213.   # log into archie.doc.ic.ac.uk archie server
  214.  
  215.   session telnet archie.doc.ic.ac.uk
  216.     waitfor "ogin:"
  217.     sendl   "archie"
  218.   sessionend
  219.  
  220.   Ok, that should make things fairly obvious. We can start multiple
  221.   sessions in a script, so if I wanted to combine the scripts and log
  222.   into archie after logging into my uni account I could use :
  223.  
  224.   session telnet loki.brunel.ac.uk
  225.     waitfor "ogin:"
  226.     ..blah..
  227.     sendl   "pine"
  228.     session telnet archie.doc.ic.ac.uk
  229.       waitfor "ogin:"
  230.       sendl   "archie"
  231.     sessionend 
  232.   sessionend
  233.  
  234.   ...or I could use the following if I just wanted to start connecting to
  235.   archie at the same time as loki :
  236.  
  237.   session telnet loki.brunel.ac.uk
  238.     waitfor "ogin:"
  239.     ..blah..
  240.     sendl   "pine"
  241.   sessionend
  242.  
  243.   session telnet archie.doc.ic.ac.uk
  244.     waitfor "ogin:"
  245.     sendl   "archie"
  246.   sessionend
  247.  
  248.   ...you can also use finger in a similar way to telnet...
  249.   
  250.   session finger mimac-03.brunel.ac.uk root
  251.   sessionend
  252.  
  253.   A simple label jump mechanism is provided (allowing simple triggering)...
  254.  
  255.   session telnet wibble.org
  256.     label   loop
  257.     waitfor "hello"
  258.     sendl   "hello to you too!"
  259.     jump    loop
  260.   sessionend 
  261.  
  262.   ...and finally there are a couple of commands I haven't mentioned :
  263.  
  264.   send "whatever"    is the same as sendl, but it does not do a linefeed
  265.                      sequence after the string.
  266.   sendf "file"       sends file - correct linefeed sequence is
  267.                      inserted where needed.
  268.   task "command"     runs command as a wimp task            
  269.   waitforc           waits until a connection is established
  270.   waitfordisconnect  waits for a session to disconnect
  271.   title "text"       sets the window title of the terminal to "text".
  272.                      This causes an error if no window is open for that
  273.                      session.
  274.  
  275.   Like the rest of FreeTerm the script language is still in development,
  276.   and will gain more commands and programming constructs as the project
  277.   continues.
  278.  
  279. 3.5.1. Points to note
  280.  
  281.   1) Once started session..endsession blocks are independant of each
  282.      other.
  283.   2) When a script is running keyboard input is not ignored.
  284.  
  285. 3.5.2. Adding Scripts to the Hotlist
  286.  
  287.   To add a script to the hotlist simply copy it to the !FreeTerm.Scripts
  288.   directory. This will result in the filename appearing after normal
  289.   hotlist entries on the menu. You can change the name in the menu by
  290.   including an alternative on the first line of a script prefixed by #$.
  291.  
  292.   eg. (one of the standard scripts)
  293.  
  294.   #$Archie (HENSA)
  295.   #
  296.   # Log into Archie server at HENSA
  297.   # Tony Howat (xargle@eh.org)
  298.   #
  299.   
  300.   session telnet archie.hensa.ac.uk
  301.     title   "Archie at HENSA (login)"
  302.     waitfor "ogin:"
  303.     sendl   "archie"
  304.     title   "Archie at HENSA"
  305.   sessionend
  306.   
  307.   # end
  308.  
  309.  
  310. 3.6. CLI options
  311.  
  312.   -debug         Traces flow negociation to terminals as per pre-release
  313.   -port <port>  
  314.   -host <host>   These two options can be used to auto start a session
  315.                  as soon as !FreeTerm is loaded.
  316.   -args <...>    Used to specify arguments if you have specified a port
  317.                  which makes use of them (ie finger)
  318.   -nopop         No pop-up resolving messages, all problems reported via
  319.                  full errors.
  320.   -vtlie         Force FreeTerm to report itself to the remote
  321.                  machine as a VT100 rather than a VT102 terminal. You
  322.                  shouldn't need this unless you're working with
  323.                  broken systems.
  324.    -nofingerurl  FreeTerm doesn't interpret some finger URLs correctly, and
  325.                  generally doesn't show the output as nicely as some web
  326.                  browsers, so it can be prevented from responding to ArcWeb
  327.                  & ANT finger URL broadcasts by using the new -nofingerurl
  328.                  command line switch.           
  329.  
  330. 3.7  The AutoRun Directory
  331.  
  332.   Files placed in the !FreeTerm.Config.AutoRun directory (or equivalent)
  333.   will be run automatically on starting FreeTerm. I use this feature for
  334.   auto starting my login script.
  335.  
  336. 4. Miscellaneous notes
  337.  
  338.   If your FreeTerm session to a unix shell gets munged try 'reset'. The
  339.   session should clear, and after a few <CR>'s you should get a normal
  340.   prompt.
  341.  
  342.   The auto close check box in the configuration window will make _telnet_
  343.   session windows close automatically if the remote end drops the
  344.   connection.
  345.  
  346.   The window finder (off the icon bar menu) gives you a list of terminal
  347.   windows open - click on one to bring it to the top.
  348.  
  349.   The VT100 keypad is useful on VMS systems etc. If you don't know what
  350.   it is or how to use it you probably don't need it.
  351.  
  352.   If you use screens and have problems with extra newlines when a character
  353.   on the last position on a line you should add "termcap LP" to .screenrc
  354.   Read the screens man page for further info.
  355.  
  356. 4.1. StrongARM Compatibility
  357.  
  358.   FreeTerm will not run properly on RISC OS 3.7 until the OS 3.7 patch
  359.   has been installed. It can be downloaded from ART's web site.
  360.  
  361.   FreeTerm also works on the Acorn NC, which is thrilling if you own one.
  362.  
  363. 4.2. Programmers' guff
  364.  
  365.   [note: you can launch sessions using ANTs URL protocol as of version 1.30
  366.          - probably much easier, but this method is slightly more flexible]
  367.  
  368.   To trigger a session via a WIMP message send Message_FreeTermOp (&440A6).
  369.   The data section should look as follows :
  370.  
  371.   length      type                      description
  372.   4 bytes     int                       action code == 2
  373.   8 bytes     empty
  374.   64 bytes    null terminated string    port name/number
  375.   80 bytes    null terminated string    destination address
  376.   80 bytes    null terminated string    the arguments
  377.   --------
  378.   236 = total length
  379.  
  380.   This message is acked if recieved by FreeTerm. OSLib example in C
  381.   follows :
  382.  
  383.   #include "oslib:user.wimp.h"
  384.   #include "kernel.h"
  385.   #include <string.h>
  386.   
  387.   #define Message_FreeTermOp 0x440a6
  388.     
  389.   typedef struct {
  390.     int action;              /* action code */
  391.     int spare1;
  392.     int spare2;
  393.     char port[64];
  394.     char dest[80];
  395.     char args[80];
  396.   } freeterm_openmsg;
  397.   
  398.   int main(void)
  399.   {
  400.     int    wimpver;
  401.     wimp_t mytaskhandle;
  402.     static wimp_block block;
  403.     wimp_message ms;
  404.     freeterm_openmsg *fom=(freeterm_openmsg *)&(ms.data);
  405.   
  406.     mytaskhandle = wimp_initialise(310,"FreeTerm Test",(void *)-1,&wimpver);
  407.   
  408.     ms.action=Message_FreeTermOp;
  409.     ms.my_ref=0;
  410.     ms.your_ref=1;
  411.     ms.sender=mytaskhandle;
  412.     strcpy(fom->port,"finger");
  413.     strcpy(fom->dest,"g7lzb.ampr.org");
  414.     strcpy(fom->args,"g7lzb");
  415.     fom->action=2;
  416.     ms.size=sizeof(freeterm_openmsg);
  417.     
  418.     wimp_send_message(wimp_USER_MESSAGE,&ms,0);
  419.   
  420.     xwimp_close_down(mytaskhandle);
  421.     return 0;
  422.   }
  423.  
  424.   The Config.Fonts file is in the format:
  425.     Name                               (string - to appear in menus)
  426.   then
  427.     zap b.m.                           (literal string)
  428.     <TermFonts$Dir>.BitMaps.X.10x20    (string)
  429.   or (for those who are prepared to tweak parameters for a while)
  430.     zap a.a.                           (literal string)
  431.     corpus.medium                      (RISC-OS font name)
  432.     10                                 Point size
  433.     16                                 Width of font
  434.     12                                 Height of font
  435.     0                                  X offset (usually 0)
  436.     8                                  Y offset (usually >0)
  437.   or
  438.     zap b.m. dir
  439.     <TermFonts$Dir>.BitMaps.CX         (Directory to find set of zap fonts)
  440.  
  441. 4.3. Internationalisation
  442.  
  443.   I would be extactic if people could provide me with resources for
  444.   different languages to be made available alongside the standard
  445.   FreeTerm distribution. e-mail them UUCoded to xargle@eh.org
  446.  
  447. 4.4. Credits
  448.  
  449.   Programming :
  450.      Tom Hughes (tom@compton.demon.co.uk) started the project.
  451.      Tony Howat (xargle@eh.org) continued it.
  452.      Merlin Hughes (hughesm@cs.unc.edu) wrote the terminal emulator.
  453.  
  454.   Thanks to :
  455.      Dominic Symes (dominic.symes@armltd.co.uk) for ZapRedraw.
  456.      Stewart Brodie (s.n.brodie@ecs.soton.ac.uk) for help with ArcWeb.
  457.      Ben Summers for help with the ColourPicker, and those on
  458.      comp.sys.acorn.programmer for sorting me out on the occasions when
  459.      I saw fit to ask particularly dumb questions.
  460.      Graham Allen for his help in sadistic terminal emulator abuse.
  461.      Pineapple Software for allocating the FreeScript filetype so promptly. 
  462.      Richard Atterer <atterer@augsburg.baynet.de> designed the curreny
  463.      default sprite set, and provided the German resources.
  464.  
  465.   ..and thanks to the beta testers for their helpful comments and
  466.     suggestions.
  467.  
  468. 5. Contacting the author(s)
  469.  
  470.   Any queries on the subject of FreeNet in general should be sent
  471.   to the original author of FreeTerm, Tom Hughes, who can be contacted by
  472.   email at freenet@compton.demon.co.uk, or by snail mail at:
  473.  
  474.       Tom Hughes
  475.       5 Lampits
  476.       Hoddesdon
  477.       Hertfordshire
  478.       EN11 8EH
  479.  
  480.   Those with basic configuration problems would be best served by the
  481.   comp.sys.acorn.networking newsgroup.
  482.  
  483.   Development of FreeTerm is being undertaken by Tony Howat, so
  484.   suggestions for enhancements and bug reports should be sent to him
  485.   by email to xargle@eh.org, or by snail mail at:
  486.  
  487.       Tony Howat
  488.       12 Dover Road
  489.       Birkdale
  490.       Southport
  491.       Merseyside
  492.       PR8 4SY
  493.  
  494.   (mail will be forwarded to my university address during term time)
  495.  
  496.   Only FreeTerm _specific_ queries should be sent to this address, I
  497.   can't help on a more general level. My setup is uniquely strange and
  498.   flakey :)
  499.  
  500.   If you are so enamoured with FreeTerm that you feel that you may like
  501.   to buy the authors a pint or three money is welcome at the above
  502.   address, it will be split fairly. (We're both impoverished students,
  503.   and so couldn't miss the chance of a beer or two for our trouble!)
  504.  
  505.   FreeTerm has a web page which should now available from the
  506.   20-20 Software home page. Point your browser at
  507.   http://www.xargle.demon.co.uk/2020
  508.  
  509.  
  510.